05. 代码规范——注释

注释

我们希望代码本身就能清晰的表达它在干什么，而不需要任何注释。

但如果你写的类、函数等需要被别人调用，亦或是代码涉及到比较深层的专业知识，那么，配上注释对保持代码的可读性是至关重要的。 注：为保证示例的丰富性，本章节选用了多种编程语言的范例代码块，在学习过程中不必过度关注语法，了解通用的代码规范即可。

• 每个类的定义和函数的声明处都应附带一份注释来描述其功能和用法（除非它们非常简洁短小），并且提醒读者在正确使用此类、函数时应当考虑的因素。当然，也可以在注释里放一小段代码来演示类和函数的基本用法。

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

• 对于复杂的操作，可以在代码块上面写上若干行注释。对于不是一目了然的代码，应在其行尾添加注释。

# 将数据中存在“|”的字符串拆分为列表。
col_names = [col for col in df] # 提取df的列名
for col in col_names: # 循环处理带“|”的数据
    try: 
        if '|' in df[col][0]:
            df[col] = df[col].apply(lambda x:str(x).split('|'))
    except:
        pass

• 但请务必注意，不要用注释来描述代码，要假设阅读代码的人比你更专业， 他只是不知道你的代码意图。以下是一个错误示范：

// Utility method that returns when this.closed is true. Throws an exception
// if the timeout is reached.
Public synchronized void waitForClose (final long timeoutMillis)
Throws Exception
{
    if(!closed)
    {
        wait(timeoutMillis);
        if(!closed)
            Throw new Exception(“MockResponseSender could not be closed”);
    }
}